home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Night of the Living Disc / Night of the Living Disc.hdv / Dev.CD.5 / Tools / Technical.Notes / IIGS / TN.IIGS.048 < prev    next >
Encoding:
Text File  |  1989-07-21  |  13.5 KB  |  291 lines  |  [04] ASCII Text (0x0000)
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIGS
  8. #48:    All About AlertWindow
  9.  
  10. Revised by:    Dave Lyons                                           July 1989
  11. Written by:    Dan Oliver & Keith Rollin                        November 1988
  12.  
  13. This Technical Note documents a new call in the Window Manager which eases the 
  14. creation of Alert windows.
  15. Changes since November 1988:  Documented new features and behavior of 
  16. AlertWindow in System Software 5.0.
  17. _____________________________________________________________________________
  18.  
  19. AlertWindow is available in Window Manager version 2.2 and later (Apple IIGS 
  20. System Disk 3.2 and later).  This call takes three parameters which are used 
  21. to create a dialog box with text, buttons, and an optional icon.
  22.  
  23. AlertWindow works by taking a pointer to an "alert string."  This alert string 
  24. defines the size and location of the alert window, specifies what icon (if 
  25. any) it uses, defines the text it displays, and indicates the number of 
  26. buttons and their names which it displays.
  27.  
  28. The alert string is a very powerful and complicated structure to be able to 
  29. specify all of this information, and it is even more powerful with the added 
  30. capability of "substitution strings."  Substitution strings work in a manner 
  31. similar to ParamText substitutions; certain sections of the text are 
  32. designated as variables to be replaced by other text when you display the 
  33. dialog.
  34.  
  35.  
  36. The Call
  37.  
  38. AlertWindow ($590E)
  39.  
  40.     input:     WORD    Space for result.
  41.                WORD    alertFlags.  Bit 0 is 0 if substitution strings are C-
  42.                        type strings (NULL terminated), 1 if they are Pascal-
  43.                        type strings (leading length byte).  Bits 1 and 2 are 
  44.                        00 if alertStrRef is a pointer, 01 if it is a handle, 
  45.                        and 10 if it is a resource ID (the resource type is 
  46.                        $8015).
  47.                LONG    Pointer to substitution string array; anything if no 
  48.                        substitutions are to be made.
  49.                LONG    alertString (see alertFlags)
  50.     output:    WORD    Button number that was selected where 0 is the first 
  51.                        button title in the alert string, 1 is the next button 
  52.                        title, and 2 is the third.
  53.  
  54.  
  55. The Format of the Alert String
  56.  
  57. Size Character
  58.  
  59. The first character of the alert string is the size character, which indicates 
  60. the size of the alert window.  The character can be ASCII 1-9 to indicate any 
  61. one of nine standard alert window sizes.  The goal of standard sizes is to 
  62. have alert windows that can contain the same amount of message text in 320 
  63. mode or 640 mode, without changing the size.  However, making this happen may 
  64. require some careful message and button text composition.
  65.  
  66.             Size Character    Approximate Maximum # of Characters
  67.             _____________________________________________________
  68.                   1                         30
  69.                   2                         60
  70.                   3                        110
  71.                   4                        175
  72.                   5                        110
  73.                   6                        150
  74.                   7                        200
  75.                   8                        250
  76.                   9                        300
  77.             _____________________________________________________
  78.  
  79. The following table shows the dimensions of the standard alert windows.  This 
  80. table gives an idea of the size of each window.  Application code should not 
  81. rely on the exact widths, heights, or position of standard windows.  If an 
  82. application needs an exact window size, it can specify zero as the size 
  83. character and use the next eight bytes as four word-sized integers which 
  84. specify the rectangle of the window.
  85.  
  86. Character    Height 320    Width 320    Height 640    Width 640
  87. _____________________________________________________________________________
  88.     1            46           152           46           200
  89.     2            62           176           54           228
  90.     3            62           252           62           300
  91.     4            90           252           72           352
  92.     5            54           252           46           400
  93.     6            62           300           54           452
  94.     7            80           300           62           500
  95.     8           108           300           72           552
  96.     9           134           300           80           600
  97.     0    (Character followed by 4 integers that represent size and position.)
  98. _____________________________________________________________________________
  99.  
  100. Icon Number
  101.  
  102. The next character is the icon number.  The icon number can be 0-9 where:
  103.  
  104.     0 =        No icon.
  105.     1 =        custom icon, followed by:
  106.                LONG    Pointer to image data.
  107.                WORD    Number of bytes image data is wide.
  108.                WORD    Number of scan lines image data is high.
  109.     2 =        Stop icon.
  110.     3 =        Note icon.
  111.     4 =        Caution icon.
  112.     5 =        Disk icon.
  113.     6 =        Disk swap icon.
  114.     7 - 9 =    Reserved--do not use.
  115.  
  116. Separator Character
  117.  
  118. The next character is a separator character.  The separator can be any 
  119. character and cannot appear in the message text or button strings.  The 
  120. separator is used to separate the message from the first button string and 
  121. each button string from each other.  For purposes of standardization the slash 
  122. (/) might be a good choice, unless you will be substituting pathnames (see the 
  123. section "Don't Use Separator Characters in Substitution Strings").
  124.  
  125. Message Text
  126.  
  127. Following the separator character is the message text.  Any characters which 
  128. LETextBox2 allows are valid in the message text.  See the section "Special 
  129. Characters" for additional message text functions.  The total size of the 
  130. message text, after string substitution, is limited to 1,000 characters.
  131.  
  132. Button Strings
  133.  
  134. The first character after the separator character following the message text 
  135. is the beginning of the first button's title.  The title can be followed with 
  136. either another separator character and button title or a string termination 
  137. character (i.e., zero (0)) to end the alert string.  A total of three button 
  138. titles may be included at the end of the alert string.  These buttons are 
  139. evenly spaced and centered at the bottom of the alert window.  The width of 
  140. each button is the same size and is set according to the widest button title.  
  141. The total size of the button text, after string substitution, is limited to 80 
  142. characters.
  143.  
  144. Termination of Alert String
  145.  
  146. A zero ($00) comes after the last button title to end the alert string.
  147.  
  148.  
  149. The Substitution Strings
  150.  
  151. The message text and button strings can contain special characters that are 
  152. replaced by substitution strings when you display the alert window.
  153.  
  154. Special Characters
  155.  
  156. The following special characters can be embedded in the message text and 
  157. button strings of an alert.  If you want the special character itself to 
  158. appear in the body of the text, enter it twice in the string.
  159.  
  160.     ^        If a caret (^) is the first character in a button 
  161.              string, the button is the default button.  The default 
  162.              button is the button selected if the user presses the 
  163.              Return key or the Enter key.  This button also has a 
  164.              bold outline on the screen.  Only one button can be 
  165.              the default button.  After the caret, the button title 
  166.              must follow like any other title (including other 
  167.              special characters).
  168.  
  169.              Note:  If the caret is to appear in the message 
  170.                     text, it must be entered twice, side-by-side.  A 
  171.                     single caret in message text has no effect and 
  172.                     is deleted from the message.
  173.  
  174.     #        Substitute with a standard string.  The pound sign (#) 
  175.              must be followed by an ASCII character.  Characters 0-
  176.              6 can be used (7-9 are reserved and should not be 
  177.              used) where:
  178.  
  179.                  #0 is replaced by OK
  180.                  #1 is replaced by Cancel
  181.                  #2 is replaced by Yes
  182.                  #3 is replaced by No
  183.                  #4 is replaced by Try Again
  184.                  #5 is replaced by Quit
  185.                  #6 is replaced by Continue
  186.  
  187.     *        Substitute with the given string.  The asterisk (*) 
  188.              followed by ASCII character in the range 0-9 denotes 
  189.              that a substitution string should be inserted at that 
  190.              point.  The asterisk and the following character are 
  191.              replaced by the corresponding string in the 
  192.              substitution array.  A pointer to the substitution 
  193.              array is one of the parameters passed to AlertWindow 
  194.              and is defined as an array of LONG pointers where:
  195.  
  196.                  LONG[0]    Pointer to the string that 
  197.                             substitutes for *0.
  198.                  LONG[1]    Pointer to the string that 
  199.                             substitutes for *1.
  200.                  LONG[2]    Pointer to the string that 
  201.                             substitutes for *2.
  202.                  LONG[3]    Pointer to the string that 
  203.                             substitutes for *3.
  204.                  LONG[4]    Pointer to the string that 
  205.                             substitutes for *4.
  206.                  LONG[5]    Pointer to the string that 
  207.                             substitutes for *5.
  208.                  LONG[6]    Pointer to the string that 
  209.                             substitutes for *6.
  210.                  LONG[7]    Pointer to the string that 
  211.                             substitutes for *7.
  212.                  LONG[8]    Pointer to the string that 
  213.                             substitutes for *8.
  214.                  LONG[9]    Pointer to the string that 
  215.                             substitutes for *9.
  216.  
  217.              Substitution strings can be a C-type (NULL-
  218.              terminated), Pascal-type (a string prefixed with a 
  219.              length byte), or Return-terminated.  NULL- and Return-
  220.              terminated strings are selected by passing 0 to 
  221.              AlertWindow as the string flag.  Pascal strings are 
  222.              selected by passing 1.
  223.  
  224.              Elements do not need to be defined if they are not 
  225.              referenced in the alert.
  226.  
  227.  
  228. Don't Use Separator Characters in Substitution Strings
  229.  
  230. Do not include a separator character in any substitution strings.  Beginning 
  231. with System Software 5.0, substitutions are performed before the alert string 
  232. is scanned for separators.  For example, if the separator character is a slash 
  233. and a pathname containing several slashes is substituted for the string, the 
  234. resulting alert will contain several more buttons than expected.
  235.  
  236.  
  237. Examples
  238.  
  239. Following are some examples of alert strings that can be passed to AlertWindow 
  240. in APW 65816 assembler syntax.
  241.  
  242. A simple alert string:
  243.  
  244.           dc    c'13/Text of Message/Button 1',il'0'---
  245.                    \     \              \              \
  246.    Size 50 high     Icon  Message        Button Title   Zero terminates alert.
  247.     by 200 wide.
  248.  
  249.                   |--------------------------------------|
  250.                   | #################################### |
  251.                   | #   ______                         # |
  252.                   | #  | Note |    Text of Message     # |
  253.                   | #  | Icon |                        # |
  254.                   | #  |______|                        # |
  255.                   | #                                  # |
  256.                   | #               _____________      # |
  257.                   | #              /             \     # |
  258.                   | #             |    Button 1   |    # |                                                         
  259.                   | #              \_____________/     # |
  260.                   | #                                  # |
  261.                   | #################################### |
  262.                   |--------------------------------------|
  263.  
  264. A more complex alert string:
  265.  
  266.     dc   c'51/This is the *0 of *3 alert *2*1 and standard'
  267.     dc   c'text called "#4" /'
  268.     dc   c'^#0,Really/*4/Yo!',il'0'
  269.     
  270. |-----------------------------------------------------------------------|
  271. | ##################################################################### |
  272. | #   ______                                                          # |
  273. | #  | Stop |    This is the message text of an alert window and      # |
  274. | #  | Icon |    standard text called "Try Again."                    # |
  275. | #  |______|                                                         # |
  276. | #                                                                   # |
  277. | #          =============       _____________      _____________     # |
  278. | #        //             \\    /             \    /             \    # |
  279. | #       ||  OK, Really   ||  |    Door #2    |  |      Yo!      |   # |                                                         
  280. | #        \\             //    \_____________/    \_____________/    # |
  281. | #          =============                                            # |
  282. | ##################################################################### |
  283. |-----------------------------------------------------------------------|
  284.  
  285.           Where substitution array =
  286.                           dc   i4'sub0,sub1,sub2,sub3,sub4'
  287.                   sub0    dc   c'message text',il'0'
  288.                   sub1    dc   c'dow',il'0'
  289.                   sub2    dc   c'win',il'13'
  290.                   sub3    dc   c'an',il'0'
  291.                   sub4    dc   c'Door #2',il'0'